4/16/98

What it is, Requirements, Retrieving from Internet, Retrieving from local database, Submitting entries, About submissions, Saving to an AppleScript, Known problems, Troubleshooting, Reporting Bugs, Distribution, Source Code, Changes.

What it is:

InCDius is a utility, written in Java, which is designed to download disc and track titles from the Internet cddb database. Once downloaded and saved into the AppleCD Audio Player's preference file, this information will be available for your favorite CD player (like Audio Strip GH) to display. The cddb does not have every CD ever made, but it is fairly good, and you can add those disks which are missing.

Requirements:

A Macintosh, preferably PowerPC based, Apple's MacOS Runtime for Java 1.5 or greater, MacOS 7.6.1 or greater, and a CD drive. Remote cddb accesses require an Internet connection without a blocking firewall.

If anybody wants to implement the native routines, this application could be ported easily to any other platform which supports Java.

Retrieving disk info from Internet database:

• To be safe, in the Finder, make a copy of the CD Remote Programs file in your Preference folder and store it away somewhere.
• Launch the InCDius GH application. Assuming that your system is properly setup, a basic CD control panel will be displayed.
• Choose "Choose Server..." from the "Database" menu.
• Click the "Get Server List" button in the dialog that appears. An updated lists of cddb servers from around the world should be downloaded. This also retrieves the current list of possible submission genres.
• Choose a nearby server from the popup menu, and click OK.
• Insert an audio CD into your CD ROM drive.
• Choose "Internet Lookup..." from the "Database" menu. If there are no errors and the given disk is listed in the database, a window with all the track names will appear. Certain disks don't quite match the entries in the database. In which case, a dialog will appear from which to choose what you believe to be the best match.
• Click the "Save" button, and the tracks will be saved to your CD Remote Programs file; eliminating any previously entered track names for this disk. Click "Save with Artist" button if you want the artist's name to be saved as part of the disk title. Click "Save to Script" if you want to use AppleScript to save the information (to FileMaker Pro for instance). Hit "Edit" if you want to edit the information and/or send a revised record back to the cddb.

Retrieving disk info from a local database:

Unfortunately, recent changes of cddb policy have limited the usefulness of this feature. There used to be a file called "xmcd-cddb.zip" available from the cddb home page which contained a copy of the entire cddb database. This file is no longer available from there. So if you don't already have a copy, you are out of luck. If you do have a copy, then you can use local database lookup to access track information when you don't have access to the network database because of a firewall or lack of network access. Unlike your local copy, the remote database is constantly being updated. So do the following only if you have no choice.

• Local database access requires certain features present in MRJ 2.0 and above. MRJ 2.0 is part of the MacOS 8.1 update and can be obtained from Apple's home page.
• Before recent changes, there was a file named "xmcd-cddb.zip" available from the cddb home page. This file is no longer available from there and I don't know where you can find a copy. If you do find a copy, do not decompress it. InCDius is smart enough to deal with the zipped version, saving you 100 MB.
• Place the "xmcd-cddb.zip" file or an alias to it (also named "xmcd-cddb.zip") in the same folder as the InCDius GH application.
• To be safe, in the Finder, make a copy of the CD Remote Programs file in your Preference folder and store it away somewhere.
• Launch the InCDius GH application. Assuming that your system is properly setup, a basic CD control panel will be displayed.
• Insert an audio CD into your CD ROM drive.
• Choose "Local Lookup..." from the "Database" menu. If there are no errors and the given disk is listed in the database, a window with all the track names will appear. It is possible that the wrong disk will be found. Sorry.
• Click the "Save" button, and the tracks will be saved to your CD Remote Programs file; eliminating any previously entered track names for this disk. Click "Save with Artist" button if you want the artist's name to be saved as part of the disk title. Click "Save to Script" if you want to use AppleScript to save the information (to FileMaker Pro for instance). Hit "Edit" if you want to edit the information and/or send a revised record back to the cddb.

Submitting Disk Info:

• Select "Submission Setup..." from the "Database" menu.
• Enter your e-mail address and the name of your e-mail server. For example, I use grhowes@xnet.com and quake.xnet.com for my setup. Use the info for your own server. Look into the settings dialog for your mail program if you've forgotten all this.
• If you want the record sent to somebody other than the cddb server, type in an e-mail address other than xmcd-cddb@amb.org in the cddb E-mail address field, but mainly leave it alone. Click OK.
• Insert an audio CD into your CD ROM drive.
• Select "Edit Disk Info..." from the "Database" menu.
• You will be presented with a window into which you can enter information about the disk and its tracks. In order to submit to the cddb, you must give each track a name, give the disk a name, and select a genre. If applicable, you should enter the artist's name. Choose which field you want to enter from the list, or hit the return key to edit the next field. You may enter any interesting information you have about the disk or its tracks in the info fields, but this is not required and in practice is rarely done.
• When a minimal amount of data has been entered, the "Submit to cddb" button will become enabled. Click when you want to start the submission protocol. Certain characters will not be accepted by the server, most notably the curly quotes and parenthesis; you will be asked to replace such characters. Please feel free to use characters like ç,á,ñ, etc. where appropriate.
• If the disk you are submitting is already in the database, you will be presented with a dialog confirming whether you want to submit a revision.
• If there was a problem with the format of the submitted record, you will be sent an e-mail detailing the problem. Please forward such messages on to me.
• You may also hit the "Save" or "Save with Artist" button to save your entered data to your local CD Remote Programs file. Hit "Save to Script" if you want to use AppleScript to save the data you've entered.

About Submissions:

I've noticed that some people do a poor job of formatting their entries to the cddb, and this annoys me. If you are going to be civic minded and submit a disk entry, then do a good job of it. There is a set of submission guidelines on the cddb home page but here are a few guidelines of my own.

• Don't capitalize all the letters. Use the capitalization rules you should have been taught in English class, or capitalize the first letter of each word or at least use the capitalization scheme that was used on the album cover if it isn't in all caps.
• Give some thought as to which genre the album falls under; I know most things seem to fall under rock, but at least think about it.
• The album title is for the album title. If the CD says "Johnny Cash Super Hits" then the title is "Super Hits", and the artist is "Johnny Cash".
• Don't put any "/" characters in the title, it will conflict with the record format. Use hyphens instead.
• Use the extended character set if indicated. La Bohème looks so much nicer than La Boheme.
• Remember that if you don't input an artist, the assumption will be made that the artist is the same as the album name. Try "various".
• Don't submit listings for your own personal mix CDs. What possible use would this info be to anyone?

About saving to a script:

Included with this package is a small AppleScript application (a scriptlet) called "InCDius Script". If you click on a "Save to Script" button, this scriptlet will be launched and given all the information that is in the cddb record. Right now, it is not programmed to do anything particularly useful with the information; it will launch the Scriptable Text Editor and put most of the info into a new text document. You may use Apple's "Script Editor" application to open the scriptlet and modify the "doMySaveData()" routine to save the data the way you like it; for example, you could tell FileMaker Pro to create a new record and save the information into it. I recommend the book "The Complete AppleScript Handbook" by Danny Goodman for those who are not AppleScript gurus.

If you received InCDius GH 1.1 final as part of the Audiofile package. Spinfree has probably replaced the scriptlet with one of their own creation.

Known Problems:

• The menu of track names does not properly show characters from the extended character set. (Fixed in MRJ 2.0).
• Sometimes the wrong menubar is displayed. Usually bringing another window forward will fix the problem.
• There are a maximum of 1100 disks that can be added to the database, but it's a bad idea to get anywhere near this limit.
• The AppleCD Audio Player application limits entered title strings to 64 characters, therefore, I enforce that limitation as well. I don't know why it does that as 255 would have worked just as well.
• FWB drivers do not work the same as Apple drivers in regards to disks with multi-media content. Track names downloaded for such disks will not show up in the Apple AudioCD Player. Also a phony data-track label might show up for the first track of such a disk in the popup menu.
• Extended character sets will not be translated properly for non-USA English systems.

Troubleshooting:

• Any problem: make sure you have MRJ 1.5 or MRJ 2.0 installed instead of MRJ 1.0.2. MRJ 1.5 users will have to use the alternative MRJAudioCD.PPC or MRJAudioCD.68K libraries.
• Error -2804: If InCDius won't startup due to this error it probably means that you have not installed MRJ properly (you might have even accidentally installed the SDK developer's kit instead).
• InCDius starts up but all it has is a blank document window and no way to quit. It's possible that there isn't enough system memory available for the Java virtual machine to startup properly. Try force quitting InCDius(command-option-escape keys all at once) and closing other applications to free up some system memory. Don't bother giving InCDius any extra application memory.
• Your choice of cddb server isn't saved when you quit InCDius: The InCDius Preferences file in your Preferences folder might have become corrupted. Throw it away and start from scratch.
• Your submission doesn't bounce but it hasn't appeared in the database after several days: Certain disks cannot be added to the cddb. Forget about it.

Reporting bugs:

Send any bug or feature requests to Glenn Howes at grhowes@kagi.com. Be sure to include information about your system configuration such as MRJ version, MacOS version, machine name, and Apple CD-ROM extension version.

Distribution:

This product is free for non-commercial distribution. Spinfree Software is permitted to distribute the final package with their product: Audiofile. Spinfree Software may also replace the "InCDius Script" application with one of their own design for redistribution.

Source Code:

The Java source for this application is available for download on my home page. The native C source is available on a per request basis.

Changes:

• Since 1.1b8
  • On an eject will now try to dismount multiple partitions.
  • Now can play Celine Dion's album: Let's Talk About Love.
  • Fixed potential problem where the CD Remote Programs file might not be properly closed.
  • As hard as this might be to believe. I was requiring the Speech Manager to be available.
  • Will now ask for confirmation if the user wants to close an edit window without saving locally.
  • Now remember screen location of control window between opening and closing.
  • Now position edit and data windows higher on the screen to be more comfortable for 640x480 screen users.
  • Support dynamic changes to the list of genre categories. So when the cddb adds new categories InCDius will be ready.
  • Now use JNI native methods. This should remove all vestige of MRJ 1.0.2 support.
  • Made the about box cuter.
• Since 1.1b7
  • Now properly save the info for Fiona Apple's Tidal album. Hopefully, this will also help other multimedia enabled CDs. I don't even like Fiona Apple, and yet I bought a copy; the things I do for my users.
  • Fixed null reference problem when a fuzzy search was required.
• Since 1.1b6
  • Worked around changes in MRJ 2.0 final which brought havoc to the layout of my data windows.
  • Changed name of machine sent to e-mail server from that of the server to the Internet name of your Mac.
  • Tried a few things to make saving track names to the CD Remote Programs file a bit more reliable.
• Since 1.1b5
  • Now a double click on the previous track button will play the previous track instead of the current track.
  • Removed 600 disk limit on entries in the database. Now using the theoretical limit of 1100. Please do not abuse this. I'm only doing this because people were doing CD Coyote merges to get around my limit anyway.
  • Will actually save time display mode and reset it.
  • Added support for local database lookup. Requires MRJ 2.0.
  • Put disk title in title bar of the control panel window.
  • Changed some of the fonts used.
  • Now give better exception warnings when a problem happens saving to the disk.
  • Changed some of the menu text.
• Since 1.1b4
  • Worked around a few bugs in MRJ 2.0 alpha 7. Should now be able to download and upload CD info.
  • Made a few revisions in the interface. I don't want any InHideous comments.
  • May have fixed problem where revision submissions were getting a mismatch between the disk ID and the track time info. Maybe not.
  • Now deal with e-mail servers which use multi-line greeting messages.
• Since 1.1b3
  • Should now not send partial submissions when a submission was canceled part way through.
  • Removed Save as Text option. This should be done with AppleScript.
  • May have fixed a rare problem with the cddb rejecting an entry due to a line being just too long.
  • Now strip the delete character from submissions.
  • Added Edit button to the database record window.
• Since 1.1b2
  • Now adds carriage return+line feed to lines sent to mail server instead of just line feeds. Should make the Eudora mail server happy.
  • Added support for using AppleScript to save a record. I'm not happy with the current implementation. Edit "InCDius Script" with the Script Editor to get it to do what you want.
• Since 1.1b1
  • Fixed problem with quitting through hitting the close box on the controls window.
  • Added Save as Text option. Does not work properly with extended characters. This saves the cddb formatted record.
  • Now removes all "control characters" except tabs and returns in entries sent to the cddb.
  • Errors thrown when saving disk info are more explanatory.
  • Command-E puts away the disk when control window foremost.
  • Replaces / with - in the default disk title for submissions.
  • Clearing the cddb e-mail address will return it to the default.
  • Added save locally with artist button to the edit submission window.